Games of Daze

home *** CD-ROM | disk | FTP | other *** search

/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / jlib_0-6 / betajlib / funclist.txt < prev next >

Wrap

Text File | 1995-04-02 | 32.3 KB | 552 lines

FUNCTION DESCRIPTIONS Copyright (C) 1995 Jonathan Paul Griffiths. All rights reserved. =============================================================================== This text file wil describe the library routines available for buffer functions, sprites, the mouse, and images. Since I've decided to re-implement the screen functions as buffer functions, I won't document the screen functions yet. There is working code for most of them in the demo directory, so consult that for the moment. Jon. p.s This document is still under construction so be patient, it might not be here yet. =============================================================================== =============================================================================== SPRITE FUNCTIONS =============================================================================== OVERVIEW Sprites are like little pictures with transparent backgrounds. When you draw them into a buffer or on to the screen, only the 'solid' part of them is seen. This makes them perfect for things like baddies and bullets in games. The JLib library provides routines to load and display sprites, as well as animating and moving them automatically. The biggest sprite you can have is currently set to 64 by 64 pixels, but you can change this if you want by changing the SPR_MAX_X and SPR_MAX_Y #defines in jlib.h. There are 2 parts to a "sprite system" in JLib. The first is the sprites themselves, the second is the frames for the sprites (the pictures). Lets have a look at how the library defines a sprite system. the sprite_system structure : typedef struct{ USHORT no_sprites; /* max number of sprites in system */ UBYTE *active_sprites; /* array of flags for active sprites */ sprite_record **sprites; /* array of the sprites themselves */ USHORT no_frames; /* num of sprite data frames in system */ sprite_data_rec **sprite_data; /* array of frame data */ }sprite_system; The sprite system is created with 2 space considerations in mind. The first is how many sprites there will be on screen (or in a buffer) at one time. Each sprite that you want needs a sprite_record structure to hold its data. The number of allowable sprites is not limited although the more sprites you add, the slower the system will become. It is a good idea for both space and speed efficiency to only create a sprite system with room for as many sprites as you will actually use. The second consideration is how many frames (or pictures) you will be using. Again It is more efficient to limit the frame numbers to the minimum you need to hold all of your frames. Utilities are provided in the utes directory that enable you to cut sprites from .PCX files and edit the sprite files created. This means you can design your sprites with almost any drawing tool you want, convert them to a .PCX and then cut them out for inclusion in your game/demo/whatever. Lets have a look at the sprite_data_rec : typedef struct{ UBYTE width; /* width of sprite */ UBYTE height; /* width of sprite */ UBYTE *data; /* x*y array of the data */ UBYTE *pattern; /* RLE storage pattern */ UBYTE no_rects; /* number of bounding rects */ UBYTE *rect_coords; /* coords of rects */ }sprite_data_rec; As you can see, it has a few extra pieces of information than just the sprites picture. For speed in handling the sprites I create a run length encoded pattern and use this pattern to help process drawing/saving/restoring operations quickly. The bounding rectangle information is for collision detection, which I have implemented but is not yet included in the library. Finally, lets look at the sprite_record structure: typedef struct{ USHORT x; /* current location */ USHORT y; UBYTE speed; /* movement speed (0 = not moving ) */ UBYTE speed_counter; BYTE xinc; /* x and y increments when moving */ BYTE yinc; UBYTE animspeed; /* animation speed (0 = not animating ) */ UBYTE animspeed_counter; UBYTE noframes; /* no of animation frames */ USHORT frame_count; USHORT frame; /* current frame */ USHORT *animframes; /* array of frames in animation */ UBYTE *buffer; /* holds the info under the sprite */ }sprite_record; This whopper needs quite a bit of information! Each sprite has its own movement and animation information which you can set. This means you can forget about having to manually animate sprites and let the system take over. Movement is done the same way as you will see later. The sprite also keeps track of its position and the information it is overwriting on a screen or in a buffer. There is just a few more things you need to know about before you examine the routines, and that is the posistion information of a sprite. because sprites need to be able to move off the side of screens or buffers, thier coordinates need to be massaged to allow this to happen. for example, a sprite at position 0,0 in a buffer would appear in the top left corner of that buffer. Because I use unsigned numbers to hold their posistion, how can this sprite continue to move out of the buffer upwards or left? The answer is that I use some trickery. Whenever you set a sprites posistion in a buffer or on a screen, add the constants SPR_MAX_X and SPR_MAX_Y to its x and y posistion first to get the posistion right. So, while we can think of a sprite at posistion 0,0 being in the top left of a buffer, the library thinks of that position as being SPR_MAX_X,SPR_MAX_Y . Now sprites can continue to move up and left from this point. I hope this make sense to you all, look at demo6 to see it in action. The exception to this system of coordinate massaging are the routines buff/screen_stamp_spriteNC and buff/screen_stencil_spriteNC, which draw a frame to a screen/buff at the coordinates given. So how do you get some sprites up and running? First, you initialise the sprite_system. Then you load some frames. Set the x and y posistion, movement and animation information for a sprite, and turn it on. Then call the appropriate save routine to capture the area where the sprite will go. Now you can draw the sprite. Restore the sprite before moving it anywhere. Normally you update sprite animation and movement after restoring the sprite and before saving the area underneath it. See demo 6 to catch this in action. Anyway, on to the routine descriptions. If you are left a little confused by anything, consult the source code. firstly, to create a sprite system: +----------------------------------------------------------------------------+ |FUNCTION:sprite_system *sprite_init(USHORT max_sprites,USHORT max_frames) | |PURPOSE: intitialises a sprite system. | |PARAMETERS: The no of sprites and frames to reserve space for. | |RETURNS: A handle to the allocated buffer or NULL if allocation failed. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function allocates memory for the system records, initialises the | | sprites, leaving then all turned off and returning the handle. | +----------------------------------------------------------------------------+ Then to load in the frames: +----------------------------------------------------------------------------+ |FUNCTION: sprite_load(char *filename,sprite_system *ssys) | |PURPOSE: load in sprite frames from a file into a sprite system. | |PARAMETERS: The filename and the sprite system | |RETURNS: A value as define in jlib.h | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function loads in the sprite frames from the given file if possible, | | create the RLE pattern for each and stores them in the sprite system. | | The format of a sprite file is easy to figure out if I don't include it in | | this release. (see the ute programs for examples | +----------------------------------------------------------------------------+ To find the next unused sprite : +----------------------------------------------------------------------------+ |FUNCTION: USHORT sprite_find_first_free(sprite_system *spr_sys) | |PURPOSE: return the number of the next free sprite. | |PARAMETERS: The sprite system. | |RETURNS: the number of the first free sprite. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function will die if there is not a free sprite left. You have been | | warned! | +----------------------------------------------------------------------------+ then: +----------------------------------------------------------------------------+ |FUNCTION: void sprite_turn_on(sprite_system *spr_sys,USHORT snum) | |PURPOSE: turn on the given sprite so it will be drawn when drawing called. | |PARAMETERS: The sprite system and the number of the sprite. | |RETURNS: nothing. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function only sets the appropriate flag for the sprite, it does not | | actually draw it to a screen or buffer. | +----------------------------------------------------------------------------+ Not forgetting at some stage you might want to : +----------------------------------------------------------------------------+ |FUNCTION: void sprite_turn_off(sprite_system *spr_sys,USHORT snum) | |PURPOSE: turn off the given sprite so it won't be drawn when drawing called.| |PARAMETERS: The sprite system and the number of the sprite. | |RETURNS: nothing. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function only clears the appropriate flag for the sprite, it does not| | actually erase it from a screen or buffer. | +----------------------------------------------------------------------------+ Also useful : +----------------------------------------------------------------------------+ |FUNCTION:void sprite_set_an_frame(sprite_system *ssys,USHORT snum,USHORT frame) | |PURPOSE: set the frame of a given sprite. | |PARAMETERS: The sprite system,the number of the sprite and the frame number.| |RETURNS: nothing. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function only sets the frame, it does not redraw the sprite with the | | new frame. Don't change the frame unless the sprite has been restored. | +----------------------------------------------------------------------------+ And : +----------------------------------------------------------------------------+ |FUNCTION:void sprite_set_xy(sprite_system *spr_sys,USHORT snum,USHORT newx,USHORT newy) |PURPOSE: set the x and y position of a given sprite. | |PARAMETERS: The sprite system,the number of the sprite, x and y. | |RETURNS: nothing. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function only sets the position, not redraw the sprite with this new | | position. Don't change the position unless the sprite has been restored. | +----------------------------------------------------------------------------+ To have the system take care of it all for you : +----------------------------------------------------------------------------+ |FUNCTION:void sprite_set_move_info(sprite_system *spr_sys,USHORT snum, | | UBYTE speed,BYTE xinc,BYTE yinc) | |PURPOSE: set up the movement info of a given sprite. | |PARAMETERS: The sprite system,sprite number ,speed, x and y increments. | |RETURNS: nothing. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | xinc and yinc will be added to the sprites position every 'speed' times | | that sprite_update_anim_and_move() is called for this sprite. A speed of | | zero means the sprite will not move at all. For example, to make a sprite | | move left 2 pixels every third update you would use: | | | | sprite_set_move_info(a_system,a_sprite,3,-2,0); | +----------------------------------------------------------------------------+ Along with this: +----------------------------------------------------------------------------+ |FUNCTION: void sprite_set_anim_info(sprite_system *spr_sys,USHORT snum, | | UBYTE anspeed,UBYTE noframes,USHORT *animpat) | |PURPOSE: set up the animation info of a given sprite. | |PARAMETERS: The sprite system,sprite num,speed,num frames and pattern | |RETURNS: nothing. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | Every 'anspeed' times that sprite_update_anim_and_move() is called for this| | sprite, the sprite will move to the next frame in animpat, which is an | | array of 'noframes' sprite frame numbers. If the end of the list is reached| | then animating will begin again from the beginning. anspeed is handled as | | for speed in sprite_set_move_info(). For example, to make a sprite swap | | between 2 frames every every fifth update you could use: | | | | #define NUM_FRAMES 2; | | USHORT animation_pattern[NUM_FRAMES] = {0,1}; | | | | sprite_set_anim_info(a_system,a_sprite,5,NUM_FRAMES,animation_pattern); | +----------------------------------------------------------------------------+ This: +-----------------------------------------------------------------------------+ |FUNCTION:void sprite_update_anim_and_move(sprite_system *spr_sys,USHORT snum)| |PURPOSE: update the movement and animation of a sprite. | |PARAMETERS: The sprite system, and the number of the sprite. | |RETURNS: nothing. | +-----------------------------------------------------------------------------+ |DESCRIPTION: | | This function only updates the position and frame of the sprite. It doesn't| | redraw the sprite with these new details.This routine should be called when| | the sprite has been restored, not while it is still drawn somewhere. | +-----------------------------------------------------------------------------+ And This: +-----------------------------------------------------------------------------+ |FUNCTION:void sprite_update_all_anim_and_move(sprite_system *spr_sys) | |PURPOSE: update the movement and animation of all active sprite. | |PARAMETERS: The sprite system. | |RETURNS: nothing. | +-----------------------------------------------------------------------------+ |DESCRIPTION: | | This function only updates the position and frame of sprites that are | | turned on. See the routine above for other warnings. | +-----------------------------------------------------------------------------+ to check if two sprites are colliding you can use: +-----------------------------------------------------------------------------+ |FUNCTION:int sprite_do_intersect(sprite_system *spr_sys,USHORT s1,USHORT s2);| |PURPOSE: see if 2 sprites are colliding using their bounding rectangles. | |PARAMETERS: The sprite system. | |RETURNS: 1 if the sprites are colliding, otherwise nothing. | +-----------------------------------------------------------------------------+ |DESCRIPTION: | | This function will only detect collisions between sprites that are turned | | on. | +-----------------------------------------------------------------------------+ =============================================================================== BUFFER FUNCTIONS =============================================================================== OVERVIEW Buffers are portions of system memory set aside to act as screens. They can be any width or height, and are only limited in size by available memory. Buffer memory is organised the same way as memory in mode 13h, that is, it is a contigous block of (width * height) unsigned chars. Thus a point in a buffer at a posistion X,Y is addressed by the formula: point memory location = buffer[ (Y*buffer width) + X] This formula is provided only to help you visualise what a buffer is, you should never access a record in the library directly, only through the functions and macros provided. This is because if I need to change a records field names (etc) then direct access code will begin to fail. Need an example? consider this: the buffer_rec type used by the library is declared thus: typedef struct{ USHORT width; /* width of buffer */ USHORT height; /* height of buffer */ UBYTE *buffer; /* the buffer */ }buffer_rec; If you wanted to know the width of a buffer, you could write something of the form: buffer_rec *buff; ... width = buff->width; /* BAD CODE */ This is bad form because if I decided to change the name of the 'width' field to 'buffer_width' your code would die. Generally I have provided macros to access the feilds of structures in the library. In this case, the correct way to get the width would be: width = B_X_SIZE(buff); This applies to all of the library structures. look in "jlib.h" to see the macros. Buffers are created using the buff_init() function. A buff_destroy() function is on its way (but not currently a priority). +----------------------------------------------------------------------------+ |FUNCTION: buffer_rec *buff_init(USHORT width,USHORT height) | |PURPOSE: Initialise an offscreen buffer | |PARAMETERS: The width and height of the buffer to be created. | |RETURNS: A handle to the allocated buffer or NULL if allocation failed. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function allocates memory for the buffer record,the buffer itself, | | fills the buffer with zeros and returns the handle. | +----------------------------------------------------------------------------+ Once the buffer is created, other fuctions may be used to draw into it. Only the draw point routines are available presently, but the others will be ported shortly. sprite functions are available now, however. +----------------------------------------------------------------------------+ |FUNCTION: void buff_draw_point(buffer_rec *buff,USHORT x, USHORT y, UBYTE c)| |PURPOSE: plot a dot at (x, y) with color c with clipping in a buffer. | |PARAMETERS: The buffer to draw to, X & Y pos and the color of the point. | |RETURNS: nothing. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | If the X or Y pos > the width or height of the buffer respectively then | | the point will not be drawn. | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |FUNCTION:void buff_draw_pointNC(buffer_rec *buff,USHORT x,USHORT y,UBYTE c) | |PURPOSE: plot a dot at (x, y) with color c without clipping in a buffer. | |PARAMETERS: The buffer to draw to, X & Y pos and the color of the point. | |RETURNS: nothing. | +----------------------------------------------------------------------------+ |DESCRIPTION: | | If the X or Y pos > the width or height of the buffer respectively then | | the program may well crash. The point may instead wrap around the buffer. | | Use with care. Slightly faster than the clipping function. | +----------------------------------------------------------------------------+ Portions of the screen can also be captured into buffers. +----------------------------------------------------------------------------+ |FUNCTION: __inline void buff_blit_screen_toNC( USHORT bfx, USHORT bfy, | | buffer_rec *buff,USHORT x1, USHORT y1,USHORT x2, USHORT y2) | |PURPOSE: blit a portion of the screen without clipping to bfx,bfy. | |PARAMETERS: The X & Y posistion to blit to in the buffer, The buffer handle| | ,two opposite corners of a rectangle in the screen. | |RETURNS: nothing | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function performs no checking. If your coordinates are not valid your| | program will most likely crash. Use with caution. | +----------------------------------------------------------------------------+ And portions of the buffer can be displayed on screen. +----------------------------------------------------------------------------+ |FUNCTION: __inline void screen_blit_buffer_to( USHORT scx, USHORT scy, | | buffer_rec *buff,USHORT x1, USHORT y1,USHORT x2, USHORT y2) | |PURPOSE: blit a portion of the buffer given to the screen with clipping | |PARAMETERS: The X & Y posistion to blit to on the screen, The buffer handle| | ,two opposite corners of a rectangle in the buffer. | |RETURNS: nothing | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function will clip the blitting rectangle to the screen and buffer. | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |FUNCTION: __inline void screen_blit_buffer_toNC( USHORT scx, USHORT scy, | | buffer_rec *buff,USHORT x1, USHORT y1,USHORT x2, USHORT y2) | |PURPOSE: blit a portion of the buffer given to the screen without clipping | |PARAMETERS: The X & Y posistion to blit to on the screen, The buffer handle| | ,two opposite corners of a rectangle in the buffer. | |RETURNS: nothing | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function does no checking - use with caution as it may cause crashes | | if given non valid coordinates. Faster than its clipping counterpart. | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |FUNCTION:void screen_blit_fs_buffer(buffer_rec *buff,USHORT x, USHORT y) | |PURPOSE: blit a buffer of width 320 to the screen. | |PARAMETERS: The X & Y posistion to blit from in the buffer. | |RETURNS: nothing | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function does no checking - use with caution as it may cause crashes | | if given non valid coordinates. Faster than its clipping counterpart. | +----------------------------------------------------------------------------+ Sprite routines can be used on buffers also. Note that in all cases, the clipping function is detailed while the non clipping version isn't. Take it as read that the non clipping versions are faster but corespondingly more dangerous with invalid input. +----------------------------------------------------------------------------+ |FUNCTION:void buff_draw_sprite(sprite_system *spr_sys, USHORT snum, | | buffer_rec *obuff); | |PURPOSE: draw a sprite on screen with clipping | |PARAMETERS:The sprite system handle, the sprite number and the target buffer| |RETURNS: nothing | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function draws the given sprite into the given buffer if it is on. | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |FUNCTION:void buff_save_sprite(sprite_system *spr_sys, USHORT snum, | | buffer_rec *obuff); | |PURPOSE: save the area that a sprite will occupy into the sprites buffer | |PARAMETERS:The sprite system handle, the sprite number and the target buffer| |RETURNS: nothing | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function saves the given sprite area from a buffer irrespective of | | whether it is on. | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |FUNCTION:void buff_rest_sprite(sprite_system *spr_sys, USHORT snum, | | buffer_rec *obuff); | |PURPOSE: restore the background area that a sprite occupied in the buffer | |PARAMETERS:The sprite system handle, the sprite number and the target buffer| |RETURNS: nothing | +----------------------------------------------------------------------------+ |DESCRIPTION: | | This function restores the given sprite area from the sprites buffer | | irrespective of whether it is turned on. | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |FUNCTION: void buff_stamp_spriteNC(USHORT x,USHORT y,sprite_system *spr_sys,| | USHORT frame,buffer_rec *obuff); | |PURPOSE: Stamp a sprite frame on a buffer without clipping | |PARAMETERS:The x and y position,sprite system handle, frame number and the | | target buffer. | |RETURNS: nothing | +----------------------------------------------------------------------------+ |DESCRIPTION: | | "stamp" means that the sprites background is drawn as zeros into the buffer| | . This routine does not alter the X and Y positions given, so sprite | | frames can't be drawn partially on the side of buffers. The main use for | | this routine is intended to be drawing game levels that are made from | | blocks stored as sprite frames. | +----------------------------------------------------------------------------+ +----------------------------------------------------------------------------+ |FUNCTION:void buff_stencil_spriteNC(USHORT x,USHORT y,sprite_system *spr_sys| | ,USHORT frame,buffer_rec *obuff); | |PURPOSE: Stencil a sprite frame on a buffer without clipping | |PARAMETERS:The x and y position,sprite system handle, frame number and the | | target buffer. | |RETURNS: nothing | +----------------------------------------------------------------------------+ |DESCRIPTION: | | "Stencil" means that the sprites background is not drawn into the buffer. | | This routine does not alter the X and Y positions given, so sprite | | frames can't be drawn partially on the side of buffers. The main use for | | this routine is intended to be drawing features that are drawn over the top| | of screens, such as font letters stored as sprite frames. | +----------------------------------------------------------------------------+ A couple of functions let you update all of the sprites in your system. They act by calling the (save,rest,draw) function once for each sprite in the system. +-----------------------------------------------------------------------------+ |FUNCTION:void buff_save_all_sprites(sprite_system *spr_sys,buffer_rec *obuff)| | |FUNCTION:void buff_rest_all_sprites(sprite_system *spr_sys,buffer_rec *obuff)| | |FUNCTION:void buff_draw_all_sprites(sprite_system *spr_sys,buffer_rec *obuff)| | |PURPOSE: Save/restore/draw all sprites to the given buffer using clipping | | routines. | |PARAMETERS:The sprite system handle and the target buffer. | |RETURNS: nothing | +----------------------------------------------------------------------------+ |DESCRIPTION: | | Essentally just a for loop. | +----------------------------------------------------------------------------+